{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 简单理解 SCF 中的 DIIS"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> 创建时间：2019-10-23"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这篇文档将会简单地叙述 GGA 为代表的 SCF DIIS。\n",
    "\n",
    "DIIS 是一种 (几乎) 专门用于自洽场过程加速的算法。关于 DIIS 的算法与数学论述，这里并不作展开。这里推荐 C. David Sherrill 的笔记 [^Sherrill-note] 与 Psi4NumPy 的 Jupyter Notebook [^psi4numpy-note] 作为拓展阅读。\n",
    "\n",
    "这篇笔记会借助 PySCF 的 DIIS 程序，对 Fock 矩阵进行外推。我们将描述在第 $t$ 步 DIIS 过程之后，如何更新第 $t+1$ 步的 Fock 矩阵。我们 **并不会** 从头写一个 DIIS 程序；这一方面是出于程序复杂性考虑，因为一般的 DIIS 程序应当要允许便利地增添、删除迭代过程中间的向量，能够处理解矩阵方程时会出现的线性依赖问题，并且要能保证一定的程序效率。另一方面，若对 DIIS 的更新过程有所了解，那么原则上我们已经理解了 DIIS 程序了，剩下的细节将只是时间与耐心上的问题。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import scipy\n",
    "from pyscf import gto, dft, lib\n",
    "from functools import partial\n",
    "\n",
    "np.einsum = partial(np.einsum, optimize=[\"greedy\", 1024 ** 3 * 2 / 8])\n",
    "np.set_printoptions(5, linewidth=150, suppress=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## PySCF 的 DIIS 使用"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 分子体系定义与 DIIS 程序"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "首先，我们的分子体系是不对称的双氧水。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "mol = gto.Mole()\n",
    "mol.atom = \"\"\"\n",
    "O  0.0  0.0  0.0\n",
    "O  0.0  0.0  1.5\n",
    "H  1.0  0.0  0.0\n",
    "H  0.0  0.7  1.0\n",
    "\"\"\"\n",
    "mol.basis = \"6-31G\"\n",
    "mol.verbose = 0\n",
    "mol.build()\n",
    "\n",
    "nao = nmo = mol.nao\n",
    "nocc = mol.nelec[0]\n",
    "nvir = nmo - nocc\n",
    "so, sv, sa = slice(0, nocc), slice(nocc, nmo), slice(0, nmo)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "为了简化程序，我们借助 PySCF 的 DFT 自洽场类 `scf_eng`，用来生成 Fock 矩阵和密度矩阵。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "scf_eng = dft.RKS(mol)\n",
    "scf_eng.xc = \"B3LYPg\"\n",
    "S = mol.intor(\"int1e_ovlp\")\n",
    "mo_occ = np.zeros(nmo)\n",
    "mo_occ[:nocc] = 2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们先简单地用下述程序展示 PySCF 中的 DIIS 是如何使用的。我们在后面会介绍 DIIS 类的具体的一些函数；这个用作演示用途的 DIIS 也时通过下述程序生成的。\n",
    "\n",
    "下面的自洽场程序取自 pyxdh 文档 [^pyxdh-note]，但作了一些修改与简化。这个自洽场程序大体思路与 Szabo [^Szabo-Ostlund.Dover.1996] 第三章的叙述契合，也与 Psi4NumPy 和 PySCF 的不少演示程序比较相似。\n",
    "\n",
    "与 Szabo 第三章叙述不太一样的地方有两处。其中一行代码是\n",
    "\n",
    "```python\n",
    "D = coef * D + (1 - coef) * D_old\n",
    "```\n",
    "\n",
    "这行代码仅仅是用来对 Naive SCF 作的修改。Szabo 的第三章可以称作是 Naive SCF，即单纯地将 Fock 矩阵对角化生成分子轨道，再得到密度代入 Fock 矩阵中。但这一行会将上一次迭代的密度 $D_{\\mu \\nu}^{t-1}$ 与这一次迭代的密度 $D_{\\mu \\nu}^{t}$ 混合，产生新的密度代入 Fock 矩阵中。这仅仅是为了防止 Naive SCF 振荡收敛，不会用于 DIIS 加速的算法。\n",
    "\n",
    "另一行代码是\n",
    "\n",
    "```python\n",
    "F = func(diis=diis, F=F, C=C, mo_occ=mo_occ)\n",
    "```\n",
    "\n",
    "这行代码是用于指定 DIIS 的更新。方式在这份文档中，DIIS 的更新方式有\n",
    "\n",
    "- `func_no_special`：Naive SCF，不引入 DIIS\n",
    "\n",
    "- `diis_err_deviation`：通过迭代过程中的 Fock 矩阵差值 $\\Delta F_{\\mu \\nu}^{t} = F_{\\mu \\nu}^{t} - F_{\\mu \\nu}^{t - 1}$ 更新 DIIS 状态\n",
    "\n",
    "- `diis_err_gradient`：通过占据-非占 Fock 矩阵 $F_{ai}^{t}$ 更新 DIIS 状态\n",
    "\n",
    "之所以用这种不太常见也不太直观的代码方式指定 DIIS 更新方式，单纯地是因为节省文档中的代码空间，避免代码冗余。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def scf_process(func, coef=1.0, maxcycle=128):\n",
    "    diis = lib.diis.DIIS()\n",
    "    \n",
    "    C = e = NotImplemented                                # Orbital (canonical) coefficient\n",
    "    D = np.zeros((nao, nao))                              # Density in this iteration\n",
    "    D_old = np.zeros((nao, nao)) + 1e-4                   # Density in last iteration\n",
    "    count = 0                                             # Iteration count (1, 2, ...)\n",
    "\n",
    "    while (not np.allclose(D, D_old)):                    # atol=1e-8, rtol=1e-5\n",
    "        if count > maxcycle:\n",
    "            raise ValueError(\"SCF not converged!\")\n",
    "        count += 1\n",
    "        D_old = D\n",
    "        F = scf_eng.get_fock(dm=D)                        # Generate initial Fock matrix from Density\n",
    "        if count > 1:                                     # avoid the case: C = NotImplemented\n",
    "            F = func(diis=diis, F=F, C=C, mo_occ=mo_occ)  # Different DIIS approaches\n",
    "            # func_no_special    : nothing happens\n",
    "            # diis_err_deviation : F = diis.update(F)\n",
    "            # diis_err_gradient  : F = diis.update(F, scf_eng.get_grad(C, mo_occ))\n",
    "        e, C = scipy.linalg.eigh(F, S)                    # Solve FC = SCe\n",
    "        D = scf_eng.make_rdm1(mo_coeff=C, mo_occ=mo_occ)  # D = 2 * C(occ).T @ C(occ)\n",
    "        D = coef * D + (1 - coef) * D_old                 # For convergence of original SCF\n",
    "            # func_no_special: D = 0.3 * D + 0.7 * D_old\n",
    "            # other cases    : nothing happens\n",
    "\n",
    "    E_tot = scf_eng.energy_tot(dm=D)\n",
    "\n",
    "    print(\"SCF Converged in     \", count, \" loops\")\n",
    "    print(\"Total energy (B3LYP) \", E_tot, \" a.u.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### DIIS 方法加速效果"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "现在我们可以来看每种 DIIS 更新方式会产生的效果了。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Naive SCF**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SCF Converged in      51  loops\n",
      "Total energy (B3LYP)  -151.37754201912352  a.u.\n"
     ]
    }
   ],
   "source": [
    "def func_no_special(*args, **kwargs):\n",
    "    return kwargs[\"F\"]\n",
    "scf_process(func_no_special, coef=0.3)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**DIIS：Fock 矩阵差值**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SCF Converged in      15  loops\n",
      "Total energy (B3LYP)  -151.37754323564036  a.u.\n"
     ]
    }
   ],
   "source": [
    "def diis_err_deviation(*args, **kwargs):\n",
    "    diis, F = kwargs[\"diis\"], kwargs[\"F\"]\n",
    "    return diis.update(F)\n",
    "scf_process(diis_err_deviation)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**DIIS：占据-非占 Fock 矩阵**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "SCF Converged in      22  loops\n",
      "Total energy (B3LYP)  -151.37754323564045  a.u.\n"
     ]
    }
   ],
   "source": [
    "def diis_err_gradient(*args, **kwargs):\n",
    "    diis, F, C, mo_occ = kwargs[\"diis\"], kwargs[\"F\"], kwargs[\"C\"], kwargs[\"mo_occ\"]\n",
    "    return diis.update(F, scf_eng.get_grad(C, mo_occ))\n",
    "scf_process(diis_err_gradient)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "尽管从原理上，使用占据-非占 Fock 矩阵的方法应当更好；但在当前的体系下 Fock 矩阵差值的方法能更快地收敛。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们能发现，若使用 PySCF 的 DIIS 类 (Psi4NumPy 的 [helper_HF.py](https://github.com/psi4/psi4numpy/blob/master/Self-Consistent-Field/helper_HF.py) 的 `DIIS_helper` 类也是相似的)，我们在实际进行 DIIS 时只需要相对于 Naive SCF 增加一行，非常方便地就可以加速收敛：\n",
    "\n",
    "```python\n",
    "F = diis.update(F)  # diis_err_deviation\n",
    "```\n",
    "\n",
    "或者\n",
    "\n",
    "```python\n",
    "F = diis.update(F, scf_eng.get_grad(C, mo_occ))  # diis_err_gradient\n",
    "```\n",
    "\n",
    "简单地说，这就是将 Fock 矩阵在每次迭代过程中，利用以前储存下来的 Fock 矩阵的信息进行再次更新。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## DIIS 细节"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "在这一段中，我们主要通过占据-非占 Fock 矩阵更新法的程序，对迭代 6 次时的 DIIS 状态进行较为细致的分析，并以此推导出第 6 次 DIIS 更新后的 Fock 矩阵。\n",
    "\n",
    "第 6 次迭代时的 DIIS 类 `diis` 与更新前的 Fock 矩阵 `F_old` $F_{\\mu \\nu}^{t=6}$、更新后的 Fock 矩阵 `F` $\\mathscr{F}_{\\mu \\nu}$ 的获得方式是通过限制迭代次数而给出的："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "diis = lib.diis.DIIS()\n",
    "\n",
    "C = e = NotImplemented                                # Orbital (canonical) coefficient\n",
    "D = np.zeros((nao, nao))                              # Density in this iteration\n",
    "D_old = np.zeros((nao, nao)) + 1e-4                   # Density in last iteration\n",
    "count = 0                                             # Iteration count (1, 2, ...)\n",
    "F_old = NotImplemented                                # Variable in last iteration\n",
    "\n",
    "while (not np.allclose(D, D_old)):                    # atol=1e-8, rtol=1e-5\n",
    "    count += 1\n",
    "    D_old = D\n",
    "    F = scf_eng.get_fock(dm=D)                        # Generate initial Fock matrix from Density\n",
    "    if count == 6:\n",
    "        F_old = F.copy()\n",
    "        F = diis.update(F, scf_eng.get_grad(C, mo_occ))\n",
    "        break\n",
    "    elif count > 1:                                   # avoid the case: C = NotImplemented\n",
    "        F = diis.update(F, scf_eng.get_grad(C, mo_occ))\n",
    "    \n",
    "    e, C = scipy.linalg.eigh(F, S)                    # Solve FC = SCe\n",
    "    D = scf_eng.make_rdm1(mo_coeff=C, mo_occ=mo_occ)  # D = 2 * C(occ).T @ C(occ)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "这里补充一个程序细节，更新后的 Fock 矩阵 $\\mathscr{F}_{\\mu \\nu}$ 也可以通过 `diis.extrapolate` 获得："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.allclose(F, diis.extrapolate().reshape(nmo, nmo))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "而 `diis.update` 除了给出更新后的 Fock 矩阵外，还将当前的 Fock 矩阵与误差信息更新入 `diis` 中，为下一次迭代的 DIIS 更新作准备。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### DIIS 储存内容"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "一般来说，DIIS 储存两部分内容：待外推信息 $p_I^t$ 与误差信息 $e_J^t$。\n",
    "\n",
    "我们在 SCF 过程中使用 DIIS 的目的是借助以前若干步迭代过程中的信息，对 Fock 矩阵作外推，得到在当前迭代步 $t$ 下更好的 Fock 矩阵。因此，待外推信息 $p_I^t$ 是第 $t$ 次迭代过程计算得到的 Fock 矩阵 $F_{\\mu \\nu}^t$。\n",
    "\n",
    "这里会有些诡异的地方是，待外推信息 $p_I^t$ 是单下标 $I$ 的向量，但原子轨道基组下的 Fock 矩阵 $F_{\\mu \\nu}^t$ 是双下标的矩阵。事实上，$p_I^t$ 在实践过程中就是将 $F_{\\mu \\nu}^t$ 压平成一维向量。待外推信息 $p_I^t$ 可以通过 `diis.get_vec` 给出，我们将这些向量整合为 `vecs` 变量中，其角标储存是 $(t, I)$："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "vecs = np.array([diis.get_vec(i) for i in range(diis.get_num_vec())])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们记每次迭代的误差信息为 $e_J^t$。对于占据-非占 Fock 矩阵更新法而言，$e_J^t$ 即是分子轨道基组下的非占-占据 Fock 矩阵 $F_{ai}^t$。我们知道，对于 SCF 收敛之后的状态下，$F_{ai} = 0$；但这在自洽场迭代过程中，该量一般地并不是零，甚至说自洽场过程就是为了达成 $F_{ai} = 0$ 的目的也不为过。因此，$F_{ai}^t$ 的状况可以看作是自洽场是否收敛得较好的判标；于是我们定义 $e_J^t$ 为压平之后的 $F_{ai}^t$。\n",
    "\n",
    "误差信息 $e_J^t$ 可以通过 `diis.get_err_vec` 给出，我们将这些向量整合为 `err_vecs` 变量中，其角标储存是 $(t, J)$："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "err_vecs = np.array([diis.get_err_vec(i) for i in range(diis.get_num_vec())])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们指出，$p_I^t$ 与 $e_J^t$ 下标所指代的维度未必要是一样的。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "(5, 484)\n",
      "(5, 117)\n"
     ]
    }
   ],
   "source": [
    "print(vecs.shape)\n",
    "print(err_vecs.shape)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{note}\n",
    "\n",
    "从上述的叙述与代码中，能看到我们只进行了 6 次迭代，其中迭代过程的误差信息与待外推信息只储存了 5 次 ($t$ 从 1 计数，外推信息的 $t \\in [2, 6]$)。我们定义当前作为迭代次数的上标 $t$ 的集合是 $\\mathscr{T} = \\{2, 3, 4, 5, 6\\}$；但在 PySCF 的 DIIS 类 `diis` 中，通过程序取出这些向量的指标时则应当使用 `0, 1, 2, 3, 4`。\n",
    "\n",
    "我们知道，DIIS 为了进行外推，会储存许多待外推信息与误差信息；但对于大分子而言，这会占用许多内存空间。出于这个目的 (以及出于收敛性的考量)，DIIS 通常只会存比较少量地待外推信息与误差信息。PySCF 的 DIIS 一般只储存 6 次迭代过程的信息。这意味着，若我们进行了 15 次迭代，待外推矩阵至多也只会储存 6 个，其余的待外推信息或误差信息都会舍去。\n",
    "\n",
    "为简化讨论，我们在这篇文档中不讨论如何舍去已经储存的待外推信息与误差信息。\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### DIIS 外推：理论"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "有了所有的待外推信息 $p_I^t$ 与误差信息 $e_J^t$ 后，我们可以作出外推结果 $\\mathscr{p}_I = \\mathscr{F}_{\\mu \\nu}$。上述公式中看似有问题的单下标转双下标可以通过互阵的 reshape 实现。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "外推的含义是\n",
    "\n",
    "$$\n",
    "\\mathscr{p}_I = \\sum_{t \\in \\mathscr{T}} w_t p_I^t\n",
    "$$\n",
    "\n",
    "$\\mathscr{T}$ 代表 DIIS 当前储存的每个外推信息对应的被迭代次数的集合，在这里恰好是从 2 开始的所有的被迭代次数。如果我们现在的迭代次数非常大，但只允许 DIIS 储存不多于 6 个待外推信息，那么求和指标 $t$ 的取值范围 $\\mathscr{T}$ 将会舍去这些迭代次数，从而保持其集合元素数量 $|\\mathscr{T}|$ 不超过 6。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们人为地引入权重 $w_t$ 以归一条件：\n",
    "\n",
    "$$\n",
    "\\sum_{t \\in \\mathscr{T}} w_t = 1\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "如果我们假定待外推的信息 $p_I^t$ 与对应的误差信息 $e_J^t$ 呈线性关系，那么被外推的信息 $\\mathscr{p}_I$ 的误差 $\\mathscr{e}_J$ 应当满足\n",
    "\n",
    "$$\n",
    "\\mathscr{e}_I = \\sum_{t \\in \\mathscr{T}} w_t e_J^t\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们希望误差 $\\Vert \\mathscr{e}_J \\Vert_2^2$ 最小化，但同时又满足 $w_t$ 的归一化条件；那么我们通过 Lagrange 乘子法，构造以下损失函数\n",
    "\n",
    "$$\n",
    "\\begin{align}\n",
    "\\mathscr{L} (\\{w_t\\}_{t \\in \\mathscr{T}}, \\lambda) &= \\Vert \\mathscr{e}_J \\Vert_2^2 + 2 \\lambda \\left( \\sum_{t \\in \\mathscr{T}} w_t - 1 \\right) \\\\\n",
    "&= \\sum_J \\sum_{t \\in \\mathscr{T}} w_t e_J^t \\cdot \\sum_{s \\in \\mathscr{T}} w_s e_J^s + 2 \\lambda \\left( \\sum_{t \\in \\mathscr{T}} w_t - 1 \\right)\n",
    "\\end{align}\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们现在定义\n",
    "\n",
    "$$\n",
    "B_{ts} = \\sum_{J} e_J^t e_J^s\n",
    "$$\n",
    "\n",
    "那么损失函数可以写为\n",
    "\n",
    "$$\n",
    "\\mathscr{L} (\\{w_t\\}_{t \\in \\mathscr{T}}, \\lambda) = \\sum_{t, s \\in \\mathscr{T}} w_t B_{ts} w_s + 2 \\lambda \\left( \\sum_{t \\in \\mathscr{T}} w_t - 1 \\right)\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "对上述损失函数求取关于 $w_t$ 的偏导数，则得到\n",
    "\n",
    "$$\n",
    "\\frac{\\partial \\mathscr{L}}{\\partial w_t} = 2 \\sum_{s \\in \\mathscr{T}} B_{ts} w_s + 2 \\lambda\n",
    "$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们显然是希望让损失函数对关于 $w_t$ 的偏导数为零；那么联立归一化条件 $\\sum_{t \\in \\mathscr{T}} w_t = 1$，我们应当得到以下矩阵方程：\n",
    "\n",
    "$$\n",
    "\\begin{align}\n",
    "\\begin{pmatrix}\n",
    "  0 & 1 & 1 & \\cdots \\\\\n",
    "  1 & B_{t_0 t_0} & B_{t_0 t_1} & \\cdots \\\\\n",
    "  1 & B_{t_1 t_0} & B_{t_1 t_1} & \\\\\n",
    "  \\vdots & \\vdots & & \\ddots \\\\\n",
    "\\end{pmatrix}\n",
    "\\begin{pmatrix}\n",
    "  \\lambda \\\\ w_{t_0} \\\\ w_{t_1} \\\\ \\vdots\n",
    "\\end{pmatrix}\n",
    "=\n",
    "\\begin{pmatrix}\n",
    "  1 \\\\ 0 \\\\ 0 \\\\ \\vdots\n",
    "\\end{pmatrix}\n",
    "\\end{align}\n",
    "$$\n",
    "\n",
    "其中，$t_0, t_1, \\cdots \\in \\mathscr{T}$ 是互不相同的指标。求解上述方程，就可以获得权重 $w_t$，进而给出 $\\mathscr{F}_{\\mu \\nu} = \\mathscr{p}_I = \\sum_{t \\in \\mathscr{T}} w_t p_I^t$，达成目标。"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### DIIS 外推：实现"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "首先，我们出，`diis` 的一个隐含变量 `diis._H` 储存的就是矩阵方程 LHS 的矩阵部分："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[ 0.     ,  1.     ,  1.     ,  1.     ,  1.     ,  1.     ],\n",
       "       [ 1.     , 22.07074, -0.48488,  0.19048, -1.05937, -0.92243],\n",
       "       [ 1.     , -0.48488, 21.30345,  0.23478,  1.63515, -0.41527],\n",
       "       [ 1.     ,  0.19048,  0.23478,  1.35725, -0.18202,  0.38307],\n",
       "       [ 1.     , -1.05937,  1.63515, -0.18202,  5.33326, -0.14979],\n",
       "       [ 1.     , -0.92243, -0.41527,  0.38307, -0.14979,  1.18526]])"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "A = diis._H[:diis.get_num_vec()+1, :diis.get_num_vec()+1]\n",
    "A"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们能很方便地构建上述矩阵的第 1 行以下、第 1 列以右的子矩阵 $B_{ts} = \\sum_{J} e_J^t e_J^s$："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "scrolled": true
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([[22.07074, -0.48488,  0.19048, -1.05937, -0.92243],\n",
       "       [-0.48488, 21.30345,  0.23478,  1.63515, -0.41527],\n",
       "       [ 0.19048,  0.23478,  1.35725, -0.18202,  0.38307],\n",
       "       [-1.05937,  1.63515, -0.18202,  5.33326, -0.14979],\n",
       "       [-0.92243, -0.41527,  0.38307, -0.14979,  1.18526]])"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "np.einsum(\"tI, sI -> ts\", err_vecs, err_vecs)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "我们可以直接解上述的矩阵方程："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([0.05123, 0.02428, 0.31624, 0.13904, 0.46921])"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "b = np.zeros(diis.get_num_vec() + 1)\n",
    "b[0] = 1\n",
    "w = np.linalg.solve(A, b)\n",
    "w = w[1:]\n",
    "w"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "那么我们可以通过 $\\mathscr{F}_{\\mu \\nu} = \\mathscr{p}_I = \\sum_{t \\in \\mathscr{T}} w_t p_I^t$ 给出外推 Fock 矩阵 `F_ex`，并且与 `diis` 给出的外推的 Fock 矩阵 `F` 进行比较："
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "F_ex = np.einsum(\"t, tI -> I\", w, vecs).reshape(nmo, nmo)\n",
    "np.allclose(F_ex, F)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    ":::{tip}\n",
    "\n",
    "在求解 DIIS 所给出的权重 $w_t$ 向量的过程中，会遇到线性依赖关系，或者说会遇到 $B_{ts}$ 数值上不满秩的情况。在这种情况下，求解矩阵方程可能会失败。\n",
    "\n",
    "一种解决方案是，干脆关闭 DIIS，使用 Naive SCF 作最后的收尾工作。由于 DIIS 已经将电子态密度收敛到相当不错的状态了，因此应当能预期这种情况下 Naive SCF 可以正常地进行收敛。\n",
    "\n",
    "另一种解决方式是对矩阵方程 $\\mathbf{A} \\boldsymbol{x} = \\boldsymbol{b}$ 的矩阵 $\\mathbf{A}$ 作对角化，并舍去其中绝对值极小的本征值与本征向量，求解一个子空间的线性方程组问题。这种解决方案应用在 PySCF 的 DIIS 程序中。\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### 对 Fock 矩阵差值方法的补充说明"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Fock 矩阵差值方法的计算过程与占据-非占 Fock 矩阵方法的实现过程几乎是相同的。唯一的区别是：\n",
    "\n",
    "- 占据-非占 Fock 矩阵方法 $e_J^t = F_{ai}^t$\n",
    "\n",
    "- Fock 矩阵差值方法 $e_J^t = \\Delta F_{\\mu \\nu}^{t} = F_{\\mu \\nu}^{t} - F_{\\mu \\nu}^{t - 1}$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "[^Sherrill-note]: <http://vergil.chemistry.gatech.edu/notes/diis/diis.pdf>\n",
    "\n",
    "[^psi4numpy-note]: <https://github.com/psi4/psi4numpy/blob/master/Tutorials/03_Hartree-Fock/3b_rhf-diis.ipynb>\n",
    "\n",
    "[^pyxdh-note]: <https://py-xdh.readthedocs.io/zh_CN/latest/qcbasic/proj_xyg3.html>\n",
    "\n",
    "[^Szabo-Ostlund.Dover.1996]: Szabo, A.; Ostlund, N. S. *Modern Quantum Chemistry: Introduction to Advanced Electronic Structure Theory (Dover Books on Chemistry)*; Dover Publications, 1996."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.3"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": false,
   "title_cell": "Table of Contents",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": false
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
